﻿namespace Lite.Messaging
{
    /// <summary>
    /// A generic interface for sending or receiving messages on a queue.
    /// </summary>
    public interface IMessageQueue
    {
        /// <summary>
        /// Queries the queue to find if the message is in a format that the
        /// queue can send.
        /// </summary>
        /// <param name="message">
        /// The message to examine.
        /// </param>
        /// <returns>
        /// True if <paramref name="message"/> is of a type that this queue can
        /// send; otherwise false.
        /// </returns>
        bool CanSend(ISendMessage message);

        /// <summary>
        /// Sends the sepcified message on this queue.
        /// </summary>
        /// <param name="message">
        /// The message to send.
        /// </param>
        void Send(ISendMessage message);

        /// <summary>
        /// Attempts to retrieve a message from the queue.
        /// </summary>
        /// <returns>
        /// A message instance if a message is available; otherwise null.
        /// </returns>
        IReceiveMessage Receive();

        /// <summary>
        /// Creates an instance of a message factory that can create message
        /// instances suitable for sending on this queue.
        /// </summary>
        /// <returns>
        /// An instance of <see cref="Lite.Messaging.IMessageFactory"/>.
        /// </returns>
        IMessageFactory GetMessageFactory();

        /// <summary>
        /// Clears all messages from the queue.
        /// </summary>
        void Purge();
    }
}